Building Hosted Recipient Queries

LISTSERV Maestro includes its own method of build queries from hosted recipient lists by using target groups. Basic or complex queries can be created to segment (filter) a hosted recipient list based on any available data. Filtering conditions are entirely optional. If no condition is supplied, the target group will always address all current subscribers of the hosted recipient list.

When a hosted recipient list is created in LISTSERV Maestro and at least one subscriber is added, the system automatically creates a target group based on that list. This target group includes all subscribers for the hosted list. It is named after the name of the hosted recipient list on which it is based, and is saved in the category <Hosted Lists Default Target Groups>. In order to filter this list, this target group must first be copied and saved. Once copied, it can be edited by clicking on its name and entering the target group definition wizard, like any other target group. For more information on using the Target Group Definition wizard, see Section 12 Introduction to Recipient Target Groups.

Make any changes desired on the General and Source screens of the wizard, and continue to the Source Details screen. As an aid for constructing the filtering condition, all profile fields available in the hosted recipient list are displayed in the upper part of the wizard page. Each profile field is listed with its name and data type. Any mandatory fields are rendered in bold. Use this list as a reference in order to decide on which fields to define conditions.

The condition itself is based on Boolean logic, meaning that when the condition is applied to a certain subscriber, the result of the condition will always be either "true" (in which case the subscriber becomes a recipient of the job in question) or "false" (in which case the subscriber will not be a recipient of the job).

The condition is defined visually in form of a "condition tree", which is displayed in the lower part of the wizard page. The condition tree consists of hierarchically ordered nodes of various types. Each of the nodes has, for a given subscriber, a certain Boolean "true" or "false" state, where for nodes that have sub-nodes, the Boolean state of the node itself is derived by combining the Boolean states of all sub-nodes in a certain manner (how they are combined depends on the type of the node itself). The root-node of the whole tree is equivalent to the whole condition, that is the Boolean result of the condition is determined by looking at the Boolean state of the root node (which in turn derives its state by looking at its subnodes and combining them accordingly, and so on).

•	Combination Operator Nodes: Such a node does not have a Boolean state itself. Instead, it derives its Boolean state by combining the states of all its subnodes. Thus its name as "Combination Operator". Such a node is never useful without any subnodes.

•

Condition Nodes: Condition nodes derive their Boolean state from the condition that is defined for them: They apply the condition to a given subscriber, which results either in "true" or "false" and thus defines the Boolean state of the node. Condition nodes never have subnodes. Condition nodes come in two varieties, normal conditions and job based conditions.

This section describes general concepts about how the condition tree is edited. The area in which the condition tree is edited is separated into two part. The tree with all its nodes is shown in the left part, while a description of the currently selected node, together with an Actions on Selected Node link is displayed in the right part. Below the two parts, a textual representation of the condition is displayed at all times. It mirrors the condition that is currently defined in a textual form, using a pseudo syntax with commonly used elements. With this representation, it is possible to verify that the condition defined by the tree is indeed the intended condition.

The tree itself always consists of elements. The top element is the root, labeled with "Subscribers of XYZ", where "XYZ" is the name of the hosted recipient list the target group is based on. The root always contains one single child node that is always a combination operator node. This "top level" operator cannot be deleted, but its type can be changed (see Combination Operator Nodes for details).

If a node in the tree has sub-nodes, then the node itself can be either closed (hiding the sub-nodes) or open (displaying the sub-nodes). Closed nodes are displayed with a small

icon, and open nodes are displayed with a small

icon. Click on the icon to open or close close a node (double-clicking the node name will not work).

Clicking on a node to select it will provide a detailed description of the node on the right side of the screen, and the Actions on Selected Node link will be displayed on the right side. Clicking on the link will open a menu that contains all currently possible actions that can be executed on the selected node. The actions available on the menu depend on the node type and the state it is in.

•

Remove Unnecessary Nodes – This action will "prune" the tree and remove any unnecessary nodes from it in a way that the Boolean logic of the tree is not changed, but that any superfluous nodes are removed. For example, any empty combination operator nodes are removed. If there are currently no unnecessary nodes, then executing this command will not have any effect. See Combination Operator Nodes for details.

•	Change Operator Type – Opens a popup dialog box that allows for changing the operator type of the node. There are four different types: AND, OR, NOT AND and NOT OR. See Combination Operator Nodes for details.

•

Cut – Marks the selected combination operator node for "Cut & Paste". When cut, the node is displayed with a "grayed" name to visualize that it has been designated for Cut & Paste. The node is not actually cut (removed from its current location) until the "Paste" command is selected at a different location. The "grayed" state is only a visual reminder that the node has been marked for "Cut". The "Cut" command is not available for the top level combination node, since this node cannot be deleted.

•

Paste – Completes an ongoing "Copy & Paste" or "Cut & Paste" operation that was previously started with either the "Cut" or the "Copy" command of a different node. Through the initial command, a node had been marked for cut or copy and executing the paste command completes the operation by actually moving the node from its old location to the currently selected combination node (for "Cut") or by creating a copy of the node in the currently selected combination node (for "Copy"). The "Paste" command itself is therefore only available if a node has been marked for “Cut & Paste” or “Copy & Paste”.

•	Clear Cut/Copy State – Aborts any ongoing Cut & Paste or Copy & Paste operation that was started with either of the commands "Cut" or "Copy". Any previously marked node will become "unmarked" and the "Paste" command will no longer be available.

•	Delete – Deletes the selected combination node and all its sub-nodes (after confirmation). This is not recoverable. The "Delete" command is not available for the top level combination node since this node cannot be deleted.

•

Insert Combination Operator – Creates a new combination operator node and inserts it as the new parent-node of the currently selected condition node. The selected condition node will initially be the only child of the freshly created combination node and the new combination node will be placed in the same parent-node as the condition node was before.

•

Cut – Marks the selected condition node for "Cut & Paste". In this state, the node is displayed with a "grayed" name to visualize that it has been designated for “Cut & Paste”. The node is not actually cut (removed from its current location) until the "Paste" command is selected at a different location. The "grayed" state is only a visual reminder that the node has been marked for "Cut".

•	Clear Cut/Copy State – Aborts any ongoing “Cut & Paste” or “Copy & Paste” operation that was started with either of the commands "Cut" or "Copy". Any previously marked node will become "unmarked" and the "Paste" command will no longer be available.

Combination operator nodes derive their Boolean state by examining the Boolean state of all sub-nodes and combining these states using a Boolean operator depending on the node's type. The following operator node types are available:

•

Combine conditions with AND – Combines the Boolean states of all sub-nodes using the boolean "AND" operator, meaning that the combination is "true" only if all sub-nodes are also "true". If even a single sub-node is "false", the combination is also "false". The AND-combination is represented in the tree with the symbol

and the textual representation "(... AND ...)".

•

Combine conditions with OR – Combines the Boolean states of all sub-nodes using the boolean "OR" operator, meaning that the combination is "true" if at least one sub-node is "true", no matter if all others are "false". If all sub-nodes are "false", the combination is also "false". The OR-combination is represented in the tree with the symbol

and the textual representation "(... OR ...)".

•

Combine conditions with AND, then negate the result – The negated version of the "AND" combination described above. If the normal "AND" results in "true", this negated version results in "false". As a result, the combination is "true" if at least one sub-node is "false", no matter if all others are "true". If all sub-nodes are "true", the combination is then "false". The negated AND-combination is represented in the tree with the symbol

and the textual representation "NOT (... AND ...)".

•

Combine conditions with OR – The negated version of the "OR" combination described above. If the normal "OR" results in "true", this negated version results in "false". As a result, the combination is "true" only if all sub-nodes are "false". If even a single sub-node is "true", the combination is then "false". The negated OR-combination is represented in the tree with the symbol

and the textual representation "NOT (... OR ...)".

When performing a “Copy & Paste’ of a combination node, the node and its whole subtree (including all sub-nodes and their sub-nodes) will be copied. Similarly, when doing a Cut & Paste, the node and its whole subtree will be removed from the original location and added at the paste location.

Certain nestings of operator nodes are superfluous and will therefore be removed ("pruned") if the Remove Unnecessary Nodes option on the Actions menu is selected on the root node. These include:

•

Combination nodes with one sub-node – Combination nodes with only a single sub-node are superfluous only if the combination node is of the non-negated sort (a simple "AND" or "OR" combination). In that case, the combination node is removed and its only sub-node takes the combination node's place directly in the parent node.

•

Combination nodes with several sub-nodes – Combination nodes with several sub-nodes are superfluous only if the combination node is of the non-negated sort (a simple "AND" or "OR" combination) and if the parent node of the combination node is of the same combination type. In that case, the combination node is removed and all its sub-nodes take the combination node's place directly in the parent node.

Normal condition nodes derive their Boolean state by examining a condition that is defined explicitly for the given node. The condition is defined when the node is first created and can later be edited by selecting the Edit command from the node's Actions on Selected Node menu. The condition node is represented in the tree with the symbol

and a textual representation that displays the condition in short form.

The Edit Condition screen shows several drop-down lists and may also contain fields or selection boxes that allow for the definition of the condition for the node. On this screen, the selection controls are organized in a hierarchical order from top to bottom, where choices in the upper controls directly influence the available choices in the lower controls. Therefore, define a condition in a top-to-bottom manner, first making selections in the upper controls, then proceeding to the next control, and so on, until the bottom of the screen is reached and the whole condition is completed.

Generally speaking, each condition consists of three parts: A left operand, an operator and a right operand. The operator is always a Boolean operator that compares the left and right operands in a certain fashion and the result is a Boolean value of "true" or "false". This operator result is then used as the Boolean state of the condition node.

In the Edit Condition screen, these three parts are represented by five controls (usually), situated above each other. The first two controls define the left operand, the third control defines the operator, and the last two controls define the right operand.

Which operators are available in the third control, and which kinds of right operands can be defined using the last two controls depends on the selections in the first two controls, that is the left operand currently selected. The following sub-sections contain descriptions of the possible choices for each of the three parts of a condition.

•

Field – The left operand is one of the profile fields available in the hosted recipient list the target group is based on. To define an operand of this type, select "the field" from the first drop-down list. The second control then becomes a drop-down list too, where you can now select the field to use.

•	Number – The left operand is a constant number. To define an operand of this type, select "the number" from the first drop-down list. The second control then becomes an edit field, where you can now enter the number value to use.

•	Text – The left operand is a constant text string. To define an operand of this type, select "the text" from the first drop-down list. The second control then becomes an edit field, where you can now enter the text string to use.

•	Boolean – The left operand is a constant Boolean value of "true" or "false". To define an operand of this type, select "the Boolean value" from the first drop-down list. The second control then becomes a drop-down list too, where you now select the Boolean value to use.

•

Formula – The left operand is a formula. When the condition is evaluated, the formula is evaluated first and its result is used as the left operand of the condition. To define an operand of this type, select "the value of the formula" from the first drop-down list. The second control then becomes a multi-line edit field, where you now enter the formula to use. See Formulas in Conditions for details about formulas.

The available operators are shown in the third control of the dialog box, which is always a drop-down list. Which operators are available depends on the type of the left operand. For example, there are different operators for numbers than for text strings.

•	contains only values of [subset "<="] The condition is true if the value-set selected in the field defined as the left operand contains only values of the set defined by the right operand. Alternatively, if the left operand set is a subset of the right operand set.

•	contains all values of [superset ">="] The condition is true if the value-set selected in the field defined as the left operand contains all values of the set defined by the right operand. Alternatively, if the left operand set is a superset of the right operand set.

•	contains some values of [intersects "&"] The condition is true if the value-set selected in the field defined as the left operand contains some values of the set defined by the right operand. Alternatively, if the intersection of the left operand set and the right operand set is not empty.

•	NOT (contains only values of) [not subset "<="] The condition is true if the value-set selected in the field defined as the left operand contains some values which do not appear in the set defined by the right operand. Alternatively, if the left operand set is not a subset of the right operand set.

•	NOT (contains all values of) [not superset ">="] The condition is true if the value-set selected in the field defined as the left operand does not contain all values of the set defined by the right operand. Alternatively, if the left operand set is not a superset of the right operand set.

•

NOT (contains some values of) [not intersects "&"] The condition is true if the value-set selected in the field defined as the left operand does not contain any of the values of the set defined by the right operand. Alternatively, if the intersection of the left operand set and the right operand set is empty.

The "subset" and "superset" operators described above (and their negated counterparts) do not adhere strictly to the mathematical definition of a subset or superset. In mathematics, the empty set is always a subset of any other set and consequently any non-empty set is always a superset of the empty set. In regard to the empty set, the above operators behave differently. For these operators, the empty set is never a subset of any other set and similarly, no set can be a superset of the empty set.

•

Formula Operators – Formulas as the operands are a special case when it comes to the operator: Normally, the left operand defines the data type and thus the available operators. For formulas however, the data type is not known until the formula is actually calculated. And with the data type not known, the available operators cannot be adjusted accordingly. Therefore, if the left operand is a formula, the available operators are the same as for "Text" (see "Text Operators" above) and the actual data type will be determined at run time, after the following rules:

•	If both operands are of Number type and the selected operator is one which is available for numbers (such as one of the normal comparison operators =, <>, <, <=, >, >=), then two operands are compared as numbers.

•	If both operands are of Number type but the selected operator is not available for numbers (it "begins with", "ends with" or "contains"), then both operands are converted to text so that the operator can be applied.

•

Field – Available if applicable. The right operand is one of the profile fields available in the hosted recipient list the target group is based on. To define an operand of this type, select "the field" from the drop-down list at fourth position. The last control then becomes a drop-down list as well, so that the field to use can be selected. This second list will automatically only contain fields of a type that are compatible to the left operand and the operator. The Field type may not be available as the right operand if there is no field that matches the data type defined by the left operand, or if the left operand is also a field but is the only field of that data type (comparisons with the same field used both for the left and right operand are not allowed).

•

Number – Only available if the left operand is of the Field type and the corresponding field is of the Number type. The right operand is a constant number. To define an operand of this type, select "the number" from the drop-down list at fourth position. The last control then becomes an edit field, where you now enter the number value to use.

•

Text – Only available if the left operand is of the Field type and the corresponding field is of the Field type. The right operand is a constant text string. To define an operand of this type, select "the text" from the drop-down list at fourth position. The last control then becomes an edit field, where you now enter the text string to use.

•

Boolean – Only available if the left operand is of the Field type and the corresponding field is of the Boolean type. The right operand is a constant Boolean value of "true" or "false". To define an operand of this type, select "the Boolean value" from the drop-down list at fourth position. The last control then becomes a drop-down list as well, so the Boolean value to use can be selected.

•

Formula – Only available if the left operand is of the Number, Text, Formula, or Field (where then in turn the corresponding field must be of the Number or Text type). The right operand is a formula. When the condition is evaluated, the formula is evaluated first and its result is used as the right operand of the condition. To define an operand of this type, select "the value of the formula" from the drop-down list at fourth position. The last control then becomes a multi-line edit field, where the formula can be entered. See Formulas in Conditions for details about formulas.

•

Parameter – Only available if the left operand is of the Field type (any kind of field). The right operand is a parameter whose content is not already defined during the condition definition, but which will be supplied later by the end-user, when the target group the condition belongs to is used in the Define Recipients wizard. See Parameters in Conditions for details about parameters.

•

Check for "empty" – Only available if the left operand is of the Field type and the corresponding field is an optional field. The right operand is the "empty" value, i.e. the condition compares the given left operand field against the empty value, using the given operator. Since only optional fields can actually be empty, this type is not available if the left operand field is a mandatory or Boolean field. To define an operand of this type, select "empty" or "the empty set" (whichever is available) from the drop-down list at fourth position. The last control then becomes invisible, because there is no more information required about the right operand.

•

Check for certain lookup table entry – Only available if the left operand is of the Field type and the corresponding field is of the Single Select type. The right operand is a fixedly selected entry from the lookup table that the left operand field is associated with. To define an operand of this type, select "the list entry" from the drop-down list at fourth position. The last control then becomes a drop-down list too, filled out with all values from the lookup table that is associated with the left operand field. Select one of the values to use from the drop-down list.

•

Check for certain lookup table entry set – Only available if the left operand is of the Field type and the corresponding field is of the Multiple Select. The right operand is a fixedly selected entry set from the lookup table that the left operand field is associated with. To define an operand of this type, select "the set of entries selected below" from the drop-down list at fourth position. The last control then becomes a multiple selection list box, filled out with all values from the lookup table that is associated with the left operand field. Select one or several of the values to use from the drop-down list (hold down CTRL or SHIFT to select multiple entries or to deselect already selected entries).

Formulas can be used in conditions to calculate the left and/or right operand value at "run time" – the moment the condition is actually applied to a given subscriber to determine if the subscriber will become one of the recipients of a job or not.

Such a formula is typed directly into the multi-line edit field provided by the condition definition dialog box. Line breaks in the formula code have no effect on the result of the formula but can be freely used to enhance readability.

The syntax follows general mathematical formula rules using operators such as "+" and "-", parenthesis nesting and so on. There are also a number of predefined "functions" that can be used in formulas.

Note: Formulas may also contain parameter placeholders, which allows for the definition of conditions with formulas, where one or several values in the formula are not known at the time the formula and condition are written, but are instead supplied later by the end user who uses this target group in the Define Recipients wizard. (See Section 18 Defining Parameters for details about how to include parameters in formulas and read the following sub-section about condition parameters in general).

Parameters can be used in conditions as the right operand in situations where the value of the operand is not yet known at the time the condition is defined (or will not be fixed by the condition definition), but will be supplied later by the end user when the target group is used in the Define Recipients wizard. Using this method can create conditions that are parameterized to allow for greater flexibility for the end user.

To define a right operand of this type, select the entry "the TYPE_VALUE supplied for the parameter" from the drop-down list at fourth position, where "TYPE_VALUE" will be filled out according to the type of the left operand field selected, which will therefore also already define the type of the parameter. The entry in the drop-down list will be one of the following:

After this selection is made, the last control becomes an edit field, where the name of the parameter to define is entered. Enter only the name, without any enclosing tags (this is different than when using a parameter in a formula or SQL statement or LISTSERV condition, where the parameter needs to be enclosed in tags to set if off from the rest of the formula/statement/condition).

Note: If you specify the same parameter name in different condition nodes, it will be interpreted as one parameter that appears several times in the condition tree; all appearances will have the same content value and must also all appear in the same type context ("Number" or "Text" and so on.). This means that if in one condition node the selection is "the text supplied for the parameter" and as the parameter name "mytext", is specified, then if same parameter name is specified again in a different condition node, the selection must also be "the text supplied for the parameter", but not for example "the numeric value supplied for the parameter". Similarly, a parameter with the same name is used in a formula somewhere else in the condition tree, then all these appearances too will reference the same parameter; all of them will be replaced with the same final content during usage in the Define Recipients wizard and must therefore have the same type.

Example: Assume that the hosted recipient list has a field called "AGE" and you want to define a target group that selects all subscribers that are of a certain age or older. If, for example, you want to test for the age of 21, you could specify this as a condition node as follows:

However, what if for the next mailing you want to use a different age, say "18" or "40"? You could of course create a new target group for that purpose, with a new condition. But this will soon become tedious, so instead, you should use a parameter for the age and thus leave it to the end user to supply the actual age to check for. The condition node would then look like this:

Where "age_param" is the name that you have given this parameter. The resulting target group could then be used to select recipients of any age or older, just by supplying the desired threshold age in an edit field, as a value for the parameter "age_param".

Job based condition nodes derive their Boolean state by examining the delivery of an earlier mail job, the so called "source job", and optionally also the tracking events collected for that job (if any). The condition node is represented in the tree with the symbol

and a textual representation that displays the condition in short form.

The source job it is that will be examined will be specified by the end user who uses the target group in the Define Recipients wizard. Here in the condition definition, it is enough to know that whatever source job will be selected, it will be a job that was in turn delivered to the same hosted recipient list as the one that this target group is based on (or more precisely, the source job used a target group which was based on the same hosted recipient list as this target group).

•

All current subscribers which were recipients of the original source job – If selected, the condition node evaluates to "true" for all subscribers currently on the hosted recipient list that have also been recipients of the source job that will be selected in the Define Recipients wizard. For any subscribers that were not recipients of the source job (because they did not fulfill the source job's condition or because they only subscribed to the list after the source job was delivered), then the condition evaluates to "false". If this choice is selected, you may optionally specify to examine the tracking events of the source job to filter further the recipients.

•

All current subscribers which were NOT recipients of the original source job – The negated version of the above condition. If selected, the condition node evaluates to "true" for all subscribers currently on the hosted recipient list that were not recipients of the source job that will be selected in the Define Recipients wizard (because they did not fulfill the source job's condition, or they only subscribed to the list after the source job was delivered). For any subscribers that were recipients of the source job, then the condition evaluates to "false".

If you select the first of the two choices above, to filter for all subscribers that were recipients of the source job, then you may optionally choose to examine the tracking events that were collected for the source job, to filter further the recipients. To enable the option, check With the following tracked behavior, and then select one of the available behavior types from the drop-down list:

•	At least one click event for any selected URL – The condition will be "true" only for subscribers who did generate at least one click event for any of the selected URLs (see below on how to select the URLs to look at).

•	At least one click event for each selected URL – The condition will be "true" only for subscribers who did generate at least one click event for each of the selected URLs (see below on how to select the URLs to look at).

•	NOT (At least one open-up event) – The negated version of the first behavior type as described above. The condition will be "true" only for subscribers who did not generate any open-up events for the source job.

•	NOT (At least one click event for any selected URL) – The negated version of the second behavior type as described above. The condition will be "true" only for subscribers who did not generate any click events for any of the selected URLs (see below on how to select the URLs to look at).

•	NOT (At least one click event for each selected URL) – The negated version of the third behavior type as described above. The condition will be "true" only for subscribers who did not generate any click events for at least one of the selected URLs (see below on how to select the URLs to look at).

If one of the click events is selected, you also need to specify which URLs to look at. This is done with the options located below the drop-down list, which only becomes enabled if such a behavior type is chosen. In this case, you have the following choices:

•

Fixed list of all tracked links of the "source job" – If selected, then the click events of all tracked links in the selected source job will be examined to determine the condition state. With this choice, the end user who employs this target group in the recipients wizard will not have the choice to define which links to examine, as it will always be all links of the source job which are examined.

•

User defined list stored in parameter – If selected, then only the click events of a certain list of links in the source job will be examined to determine the condition state. Which links will appear in this list is not defined here, at the time the condition is specified, but is instead defined by the end-user who employs this target group in the Define Recipients wizard by filling out a parameter. The parameter's name needs to be specified here, together with the selected option. Later in the Define Recipients wizard, the selection of links will be made in a multiple selection box, and the resulting list of links to examine will be stored in the parameter with the name specified here. The condition will then look at the list in this parameter to determine its Boolean state.

Note: If you specify the same parameter name in different job based condition nodes, it will be interpreted as one parameter that appears several times in the condition tree; all appearances will be filled out with the same list of selected links (depending on the end-user's choices). A parameter with the same name in a normal condition node or a condition formula may not be used.

With this option enabled, the choice for the "source job" becomes more limited. Normally for job based conditions, a possible source job is one that has been delivered to the same hosted recipient list as the one the target group is based on. When using the "examine tracking events" option, the choice for the source job is narrowed to all the above jobs which also had personal tracking enabled at the time of delivery. Only the information collected with personal tracking is sufficient for the job based condition node to determine if the condition will be "true" or "false".

With this option enabled, a decision must be made for "which" events to actually take into consideration. Will all events collected for the source job be used, or only some?
To answer this question, the following happens whenever you define a job based condition which shall also examine tracking events:

If the condition tree contains at least one such job based condition node, additional input controls are displayed on the wizard page, right below the condition tree. These controls give you the option of defining a time period into which events of the source job must fall to actually be considered by the job based condition nodes in the tree. (The settings made here apply equally to all job based condition nodes in the tree that examine tracking events.)

•	The delivery time of the original source job – This means that the event period begins with the delivery time of the source job; the earliest events generated for the source job will be considered by the condition.

•

<To be defined during recipient definition> – This means that the beginning of the event period (the "From" threshold) is not already fixed here in the target group definition but will instead be supplied by the end user who employs this target group in the Define Recipients wizard. The end user will then have the choice to set the "From" threshold to the same "delivery time of the original source job" as explained above (to catch even the earliest events) or to set it to a specific date and time (to start event examination at this specific time).

•

The delivery time of the follow-up job – The "follow-up job" is the job that this target group will be employed for in the Define Recipients wizard. This choice means that the event period ends with the delivery time of the follow-up job; even the latest events generated for the source job will be considered by the condition.

•

<To be defined during recipient definition> – This means that the end of the event period (the "To" threshold) is not already fixed here in the target group definition but will instead be supplied by the end user who employs this target group in the Define Recipients wizard. The end user will then have the choice to set the "To" threshold to the same "delivery time of the follow-up job" as explained above, (to catch even the latest events) or to set it to a specific date and time (to end event examination at this specific time).